Fritz: All Fritz/All Fritz.zip/All Fritz/FILES/PROGMISC/FPCHELP.LZH/KERNEL3.HLP

Text File | 1988-08-01 | 16KB | 433 lines

KERNEL3.HLP            Edited by J. McKnight    1988-01-30 23:32

>TYPE           ( addr len -- )
        TYPE for multitasking systems.

.(              ( -- )
        Type the following string on the terminal.

(               ( -- )
        The Forth Comment Character. The input stream is skipped  until a ) is
        encountered.

TRAVERSE        ( addr direction -- addr' )
        Run through a name field in the specified direction. Terminate when a
        byte whose high order bit is on is detected.

DONE?           ( n -- f )
        True if the input stream is exhaused or state doesn't match.

CNHASH          ( cfa -- ya )
        Given CFA, get pointer into >NAME hash table in YSEG.

CNSRCH          ( cfa ya maxya -- nfa failf )
        Search for CFA between YA and MAXYA in YSEG. Return NFA and failure
        flag.

N>LINK          ( anf -- alf)
        Go from name field address anf to link field address alf.

L>NAME          ( alf -- anf )
        Go from link field address alf to name field address alf.

BODY>           ( apf -- acf )
        Go from body address apf to code field address acf.

NAME>           ( anf -- acf )
        Go from name field address anf to code field address acf.

LINK>           ( alf -- acf )
        Go from link field address alf to code field address acf.

>BODY           ( acf -- apf )
        Go from code field address acf to body address apf.

NO-NAME         ( --- )
        A dummy name, whose name field address is returned by >NAME
        when the real name field can not be found.

>NAME           ( acf -- anf )
        Go from code field address acf to name field address anf.

>LINK           ( acf -- alf )
        Go from code field address acf to link field address alf.

>VIEW           ( acf -- avf )
        Go from code field address acf to view field address avf.

VIEW>           ( avf -- acf )
        Go from view field address avf to code field address acf.

HASH            ( str-addr voc-ptr -- thread )

        Given a string address and a pointer to a set of vocabulary chains,
        returns the actual thread. The hash algorithm used is as follows:

                (((firstchar*2)+secondchar)*2)+count)and(#threads-1)

        This seems to provide a good distribution across the 64 threads in
        1000 word FORTH vocabulary.


(FIND)          ( here alf --- cfa flag | here false )
        Does a search of the dictionary based on a pointer to a vocabulary
        thread and a string.  If it finds the string in the chain, it returns
        a pointer to the CFA field inside the header. This field contains the
        code field address of the body. If it was an immediate word the flag
        returned is a 1. If it is non-immediate the flag returned is a -1. If
        the name was not found, the string address is returned along with a
        flag of zero. Note that links point to links, and are absolute
        addresses.

FIND            ( addr -- cfa flag | addr false )
        Run through the vocabulary list searching for the name whose address
        is supplied on the stack. If the name is found, return the code field
        address of the name and a non-zero flag. The flag is -1 if the word is
        non-immediate and 1 if it is immediate. If the name is not found, the
        string address is returned along with a false flag.

DEFINED         ( -- here 0 | addr false )
        Look up the next word in the input stream. Return true if it exists,
        otherwise false. Maybe ignore case.

?STACK          ( -- )
        Check for parameter stack underflow or overflow and issue appropriate
        error message if detected.

STATUS          ( -- )
        Indicate the current status of the system.

INTERPRET       ( -- )
        The Forth Interpret Loop. If the next word is defined, execute it,
        otherwise convert it to a number and push it onto the stack.

PRINT           <words-to-be-interpreted> ( -- )
        Interpret the following words, and output to printer.

ALLOT           ( n -- )
        Allocate more space in the dictionary.

,               ( n -- )
        Set the contents of the dictionary to the arbitrary 16-bit value on
        the stack.

C,              ( char -- )
        Same as , except uses an 8-bit value.

ALIGN           ( -- )
        Used to force even addresses. A noop on the 8086.

EVEN            ( -- )
        Makes the top of the stack an EVEN number. A noop on the 8086.

COMPILE         <name> ( -- )
        Compile the (typically not-immediate) following word <name> when this
        definition executes. Name is later compiled into the LIST dictionary
        space.

CCOMPILE                ( -- )
        Compile the (typically not-immediate) following word <name> when this
        definition executes. Name is later compiled into the CODE dictionary
        space.  This is a special purpose version of COMPILE, used when
        compiling something into the CODE area.

IMMEDIATE       ( -- )
        Mark the last Header as an Immediate word.

LITERAL         ( n -- )
        Compile the single integer from the stack as a literal.

DLITERAL        ( d# -- )
        Compile the double integer from the stack as a literal.

ASCII           <char> ( -- n )
        Compile the next character in the input stream as a literal ASCII
        integer.

CONTROL         <char> ( -- n )
        Compile the next character in the input stream as a literal ASCII
        Control Character.

CRASH           ( -- )
        Default routine called by execution vectors.

?MISSING        ( f -- )
        Tell user the word does not exist.

'               <name> ( -- cfa )
        Return the code field address of the next word <name>.

[']             <name> ( -- )
        Like ' only used while compiling

[COMPILE]       <name> ( -- )
        Force compilation of an immediate word

(")             <string> ( -- addr len )
        Return the address and length of the inline string, and continue
        execution after the string.

(.")            <string> ( -- )
        Type the inline string, and continue execution after the string.

,"              <string> ( -- )
        Add the following text string till a " to the dictionary.

."              <string> ( -- )
        Compile the string till a " to be typed out later.

"               <string> ( -- )
        Compile the string. Return address and length at runtime.

">$             ( a1 len -- a2 )
        Convert address a1 and length len of a string created with "
        into a counted string address a2.  This word relys on the fact
        that " really creates counted strings, but converts them to
        address and length on execution.

FENCE   is the limit address for forgetting.

TRIM            ( faddr voc-addr -- )
        ????? Change the 4 hash pointers in a vocabulary so that they are all
        less than a specified value, faddr.

(FRGET)         ( code-addr relative-link-addr )
        Forgets part of the dictionary. Both the code address and the header
        address are specified, and may be independent. (FRGET) resets all of
        the links and releases the space.

FORGET          <name> ( -- )
        Forget all of the code and headers before <name>. FORGET must be
        used with caution, if you are using DEFERS or UDEFERS, FORGET
        will not know about these chains, so they must be unlinked before
        using FORGET or disaster WILL strike.

WHERE           ( ?????
        ????? Locates the screen and position following an error.

?ERROR          ( ?????
        Maybe indicate an error. Change this to alter ABORT"

(?ERROR)        ( ?????
        Default for ?ERROR. Conditionally execute WHERE and type message.

(ABORT")        ( f -- )
        The Runtime code compiled by ABORT". Uses ERROR, and updates return
        stack.

ABORT"  <message>"      ( f -- )
        If the flag is true, issue <message> and ABORT.

ABORT           ( -- )
        Clear the data stack and QUIT; no message is displayed.

?CONDITION      ( f -- )
        Simple compile time error checking. Usually adequate.

>MARK           ( -- addr )
        Set up for a Forward Branch.

>RESOLVE                ( addr -- )
        Resolve a Forward Branch.

<MARK           ( -- addr )
        Set up for a Backwards Branch.

<RESOLVE        ( addr -- )
        Resolve a Backwards Branch.

?>MARK          ( -- f addr )
        Set up a forward Branch with Error Checking.

?>RESOLVE       ( f addr -- )
        Resolve a forward Branch with Error Checking.

?<MARK          ( -- f addr )
        Set up for a Backwards Branch with Error Checking.

?<RESOLVE       ( f addr -- )
        Resolve a backwards Branch with Error Checking.

LEAVE           ( -- )
        Immediately exit a DO-LOOP.

?LEAVE          ( f -- )
        Immediately exit a DO-LOOP if the flag is true; else continue looping.

BEGIN           ( -- )
        Used in the form            BEGIN ... AGAIN,
                                or  BEGIN ... flag UNTIL,
                                or BEGIN ... flag WHILE ... REPEAT

AGAIN           ( -- )
        Unconditional jump to just after BEGIN in a BEGIN ... AGAIN loop.

UNTIL           ( ? -- )
        Marks end of a BEGIN ... UNTIL loop; terminate if flag ? is true.

WHILE           ( ? -- )
        Used in the form  BEGIN <loop> flag WHILE <true> REPEAT.
        Repeat <loop> and <true> clauses while the flag ? is true (really,
        non-zero).

REPEAT          ( -- )
        Unconditional backward branch to just after BEGIN in a
        BEGIN  <loop>  flag WHILE  <true>  REPEAT   loop.

DO              ( limit start -- )
        Initialize a loop structure with index running from start to limit-1.
        Used in the form   DO ... LOOP   or  DO ... +LOOP

?DO             ( limit start -- )
        Same as DO except that the loop will not be executed if start = lim.

LOOP            ( -- )
        Terminate a loop structure. Increment loop index by one and repeat
        <loop-body> until loop index crosses the boundary between limit and
        limit - 1.
        Used in the form   DO <loop-body> LOOP.

+LOOP           ( n -- )
        Terminate a loop structure. Increment loop index by n and repeat
        <loop-body> until loop index crosses the boundary between limit and
        limit - 1.
        Used in the form   DO <loop-body> LOOP.

IF              ( ? -- )
        Used in the form: ?   IF <true> ELSE <false> THEN  (ELSE is optional).
        If flag ? is false, branches forward to <false> or after THEN.

ELSE            (
        Used in the form: ? IF <true> ELSE <false> THEN. If flag ? is false,
        branches forward to <false>.

THEN            ( -- )
        Terminate a branch structure.
        Used in the form   flag IF ... ELSE ... THEN

,VIEW           ( -- )
        Calculate and compile the VIEW field of the header.

"HEADER         <name> ( -- )
        The string <name> to make a header, and initialize  the code field.
        First we check for duplicates. Then we make  entry in >NAME hash
        table if appropriate. Next lay down the  view field. Then we hook
        in to the correct thread an make the  link field. We set up LAST so
        that it points to our name  field. Then we copy the name to YSEG and
        delimit the name  field bits. Then we make the pointer in the YSEG to
        the CFA.  Then we add a stopper entry to >NAME hash table in case of
        a large ALLOT or end of dictionary. Does all of its work in HEAD
        space, has no effect on CODE space whatsoever.

,CALL           ( -- )
        Compiles a CALL to address ZERO, the actual branch address is set
        later by ;USES or ;CODE.  See CREATE, VARIABLE, CONSTANT & :

,JUMP           (
        Compiles a JMP to address ZERO, the actual jump address is set
        later by ;USES or ;CODE.  See CREATE, VARIABLE, CONSTANT & :

HEADER          <name> ( -- )
        Creates a NAME header in HEAD space, but compiles absolutely
        nothing in CODE space.  The head created, does point at HERE
        though.

CREATE          <name> ( -- )
        Make a header for the next word in the input stream.

!CSP            ( -- )
        Save the current stack level for error checking.

?CSP            ( -- )
        Issue error message if stack has changed.

HIDE            ( -- )
        Removes the Last definition from the Header Dictionary.

REVEAL          ( -- )
        Activates the Last definition in the Header Dictionary.

(;USES)         ( -- )
        Set the code field to the contents of following cell

;USES           ( -- )
        Similar to the traditional ;CODE except used when  run time code has
        been previously defined.

(;CODE)         ( -- )
        Set the code field to the address of the following.

;CODE           ( -- )
        Used for defining the run time portion of a defining  word in low
        level code.

DOES>           ( -- )
        Specifies the run time of a defining word in high  level Forth.

ASSEMBLER       ( --- )
        The VOCABULARY that contains all of the assembler definitions.

[               ( -- )
        Stop compiling and start interpreting.

]               ( -- )
        The Compiling Loop. First sets Compile State. Looks up the next word
        in the input stream and either executes it or compiles it depending
        upon whether or not it is immediate. If the word is not in the
        dictionary, it converts it to a number, either single or double
        precision depending on whether or not any punctuation was present.
        Continues until input stream is empty or state changes.

MAKEDUMMY       <name> ( -- )
        Make a dummy : definitions out of <name>.  Effectively a NOOP,
        used by ANEW.

ANEW            <name> ( -- )
        Define A NEW definition <name>.  If <name> already exists, then
        we FORGET it before making the new one.  A nice utility to allow
        re-loading a file again and again for debugging purposes.  I don't
        know where this furst originated, but I learned of it from
        RAY ISAAC at CALOS, a real neat trick.

:               ( -- )
        Defines a colon definition. The definition is hidden until it is
        completed, or the user desires recursion. The runtime for : adds a
        nesting level.

;               ( -- )
        Terminates a colon definition. Compiles the runtime code to remove a
        nesting level, and changes STATE so that compilation will terminate.

RECURSIVE       ( -- )
        Allow the current definition to be self referencing.

CONSTANT        <name> ( n -- )
        A defining word that creates constants. At runtime the value of the
        constant is placed on the stack.

VARIABLE        <name>  ( -- )
        A defining word to create variables. At runtime the address of the
        variable is placed on the stack.

DEFER           <name> ( -- )
        Define a vectored execution word. These are initially set to display
        an error message. They are initialized with IS.

VOCABULARY      ( -- )
        Defines a new Forth vocabulary.

DEFINITIONS     ( -- )
        Subsequent definitions will be placed into CURRENT.

2CONSTANT       <name> ( d# -- )
        Create a double number constant.

2VARIABLE       <name> ( -- )
        Create a double length variable.

RUN             ( --- )
        Interpret or compile whatever is in the TERMINAL INPUT BUFFER.
        Tests STATE, and does the appropriate thing.